home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 26
/
Cream of the Crop 26.iso
/
os2
/
octa209b.zip
/
octave-2.09
/
doc
/
octave.i06
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1997-08-20
|
51KB
|
992 lines
This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.
START-INFO-DIR-ENTRY
* Octave: (octave). Interactive language for numerical computations.
END-INFO-DIR-ENTRY
Copyright (C) 1996, 1997 John W. Eaton.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
File: octave, Node: Integer Conversions, Next: Floating-Point Conversions, Prev: Table of Output Conversions, Up: C-Style I/O Functions
Integer Conversions
-------------------
This section describes the options for the `%d', `%i', `%o', `%u',
`%x', and `%X' conversion specifications. These conversions print
integers in various formats.
The `%d' and `%i' conversion specifications both print an numeric
argument as a signed decimal number; while `%o', `%u', and `%x' print
the argument as an unsigned octal, decimal, or hexadecimal number
(respectively). The `%X' conversion specification is just like `%x'
except that it uses the characters `ABCDEF' as digits instead of
`abcdef'.
The following flags are meaningful:
Left-justify the result in the field (instead of the normal
right-justification).
For the signed `%d' and `%i' conversions, print a plus sign if the
value is positive.
For the signed `%d' and `%i' conversions, if the result doesn't
start with a plus or minus sign, prefix it with a space character
instead. Since the `+' flag ensures that the result includes a
sign, this flag is ignored if you supply both of them.
For the `%o' conversion, this forces the leading digit to be `0',
as if by increasing the precision. For `%x' or `%X', this
prefixes a leading `0x' or `0X' (respectively) to the result.
This doesn't do anything useful for the `%d', `%i', or `%u'
conversions.
Pad the field with zeros instead of spaces. The zeros are placed
after any indication of sign or base. This flag is ignored if the
`-' flag is also specified, or if a precision is specified.
If a precision is supplied, it specifies the minimum number of
digits to appear; leading zeros are produced if necessary. If you
don't specify a precision, the number is printed with as many digits as
it needs. If you convert a value of zero with an explicit precision of
zero, then no characters at all are produced.
File: octave, Node: Floating-Point Conversions, Next: Other Output Conversions, Prev: Integer Conversions, Up: C-Style I/O Functions
Floating-Point Conversions
--------------------------
This section discusses the conversion specifications for
floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
conversions.
The `%f' conversion prints its argument in fixed-point notation,
producing output of the form [`-']DDD`.'DDD, where the number of digits
following the decimal point is controlled by the precision you specify.
The `%e' conversion prints its argument in exponential notation,
producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD. Again, the
number of digits following the decimal point is controlled by the
precision. The exponent always contains at least two digits. The `%E'
conversion is similar but the exponent is marked with the letter `E'
instead of `e'.
The `%g' and `%G' conversions print the argument in the style of
`%e' or `%E' (respectively) if the exponent would be less than -4 or
greater than or equal to the precision; otherwise they use the `%f'
style. Trailing zeros are removed from the fractional portion of the
result and a decimal-point character appears only if it is followed by
a digit.
The following flags can be used to modify the behavior:
Left-justify the result in the field. Normally the result is
right-justified.
Always include a plus or minus sign in the result.
If the result doesn't start with a plus or minus sign, prefix it
with a space instead. Since the `+' flag ensures that the result
includes a sign, this flag is ignored if you supply both of them.
Specifies that the result should always include a decimal point,
even if no digits follow it. For the `%g' and `%G' conversions,
this also forces trailing zeros after the decimal point to be left
in place where they would otherwise be removed.
Pad the field with zeros instead of spaces; the zeros are placed
after any sign. This flag is ignored if the `-' flag is also
specified.
The precision specifies how many digits follow the decimal-point
character for the `%f', `%e', and `%E' conversions. For these
conversions, the default precision is `6'. If the precision is
explicitly `0', this suppresses the decimal point character entirely.
For the `%g' and `%G' conversions, the precision specifies how many
significant digits to print. Significant digits are the first digit
before the decimal point, and all the digits after it. If the
precision is `0' or not specified for `%g' or `%G', it is treated like
a value of `1'. If the value being printed cannot be expressed
precisely in the specified number of digits, the value is rounded to
the nearest number that fits.
File: octave, Node: Other Output Conversions, Next: Formatted Input, Prev: Floating-Point Conversions, Up: C-Style I/O Functions
Other Output Conversions
------------------------
This section describes miscellaneous conversions for `printf'.
The `%c' conversion prints a single character. The `-' flag can be
used to specify left-justification in the field, but no other flags are
defined, and no precision or type modifier can be given. For example:
printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");
prints `hello'.
The `%s' conversion prints a string. The corresponding argument
must be a string. A precision can be specified to indicate the maximum
number of characters to write; otherwise characters in the string up to
but not including the terminating null character are written to the
output stream. The `-' flag can be used to specify left-justification
in the field, but no other flags or type modifiers are defined for this
conversion. For example:
printf ("%3s%-6s", "no", "where");
prints ` nowhere ' (note the leading and trailing spaces).
File: octave, Node: Formatted Input, Next: Input Conversion Syntax, Prev: Other Output Conversions, Up: C-Style I/O Functions
Formatted Input
---------------
Octave provides the `scanf', `fscanf', and `sscanf' functions to
read formatted input. There are two forms of each of these functions.
One can be used to extract vectors of data from a file, and the other
is more `C-like'.
- Built-in Function: [VAL, COUNT] = fscanf (FID, TEMPLATE, SIZE)
- Built-in Function: [V1, V2, ...] = fscanf (FID, TEMPLATE, "C")
In the first form, read from FID according to TEMPLATE, returning
the result in the matrix VAL.
The optional argument SIZE specifies the amount of data to read
and may be one of
`Inf'
Read as much as possible, returning a column vector.
`NR'
`[NR, Inf]'
Read as much as possible, returning a matrix with NR rows.
If the number of elements read is not an exact multiple of
NR, the last column is padded with zeros.
`[NR, NC]'
Read up to `NR * NC' elements, returning a matrix with NR
rows. If the number of elements read is not an exact multiple
of NR, the last column is padded with zeros.
If SIZE is omitted, a value of `Inf' is assumed.
A string is returned if TEMPLATE specifies only character
conversions.
The number of items successfully read is returned in COUNT.
In the second form, read from FID according to TEMPLATE, with each
conversion specifier in TEMPLATE corresponding to a single scalar
return value. This form is more `C-like', and also compatible
with previous versions of Octave.
- Built-in Function: [VAL, COUNT] = sscanf (STRING, TEMPLATE, SIZE)
- Built-in Function: [V1, V2, ...] = sscanf (STRING, TEMPLATE, "C")
This is like `fscanf', except that the characters are taken from
the string STRING instead of from a stream. Reaching the end of
the string is treated as an end-of-file condition.
- Built-in Function: [VAL, COUNT] = scanf (TEMPLATE, SIZE)
- Built-in Function: [V1, V2, ...] = scanf (TEMPLATE, "C")
This is equivalent to calling `fscanf' with FID = `stdin'.
It is currently not useful to call `scanf' in interactive programs.
Calls to `scanf' are superficially similar to calls to `printf' in
that arbitrary arguments are read under the control of a template
string. While the syntax of the conversion specifications in the
template is very similar to that for `printf', the interpretation of
the template is oriented more towards free-format input and simple
pattern matching, rather than fixed-field formatting. For example,
most `scanf' conversions skip over any amount of "white space"
(including spaces, tabs, and newlines) in the input file, and there is
no concept of precision for the numeric input conversions as there is
for the corresponding output conversions. Ordinarily, non-whitespace
characters in the template are expected to match characters in the
input stream exactly.
When a "matching failure" occurs, `scanf' returns immediately,
leaving the first non-matching character as the next character to be
read from the stream, and `scanf' returns all the items that were
successfully converted.
The formatted input functions are not used as frequently as the
formatted output functions. Partly, this is because it takes some care
to use them properly. Another reason is that it is difficult to recover
from a matching error.
File: octave, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input, Up: C-Style I/O Functions
Input Conversion Syntax
-----------------------
A `scanf' template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with `%'.
Any whitespace character in the template causes any number of
whitespace characters in the input stream to be read and discarded.
The whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string. For example,
write ` , ' in the template to recognize a comma with optional
whitespace before and after.
Other characters in the template string that are not part of
conversion specifications must match characters in the input stream
exactly; if this is not the case, a matching failure occurs.
The conversion specifications in a `scanf' template string have the
general form:
% FLAGS WIDTH TYPE CONVERSION
In more detail, an input conversion specification consists of an
initial `%' character followed in sequence by:
* An optional "flag character" `*', which says to ignore the text
read for this specification. When `scanf' finds a conversion
specification that uses this flag, it reads input as directed by
the rest of the conversion specification, but it discards this
input, does not use a pointer argument, and does not increment the
count of successful assignments.
* An optional decimal integer that specifies the "maximum field
width". Reading of characters from the input stream stops either
when this maximum is reached or when a non-matching character is
found, whichever happens first. Most conversions discard initial
whitespace characters (those that don't are explicitly
documented), and these discarded characters don't count towards
the maximum field width.
* An optional type modifier character. This character is ignored by
Octave's `scanf' function, but is recognized to provide
compatibility with the C language `scanf'.
* A character that specifies the conversion to be applied.
The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers. See the descriptions
of the individual conversions for information about the particular
options that they allow.
File: octave, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: C-Style I/O Functions
Table of Input Conversions
--------------------------
Here is a table that summarizes the various conversion
specifications:
Matches an optionally signed integer written in decimal. *Note
Numeric Input Conversions::.
Matches an optionally signed integer in any of the formats that
the C language defines for specifying an integer constant. *Note
Numeric Input Conversions::.
Matches an unsigned integer written in octal radix. *Note Numeric
Input Conversions::.
Matches an unsigned integer written in decimal radix. *Note
Numeric Input Conversions::.
`%x', `%X'
Matches an unsigned integer written in hexadecimal radix. *Note
Numeric Input Conversions::.
`%e', `%f', `%g', `%E', `%G'
Matches an optionally signed floating-point number. *Note Numeric
Input Conversions::.
Matches a string containing only non-whitespace characters. *Note
String Input Conversions::.
Matches a string of one or more characters; the number of
characters read is controlled by the maximum field width given for
the conversion. *Note String Input Conversions::.
This matches a literal `%' character in the input stream. No
corresponding argument is used.
If the syntax of a conversion specification is invalid, the behavior
is undefined. If there aren't enough function arguments provided to
supply addresses for all the conversion specifications in the template
strings that perform assignments, or if the arguments are not of the
correct types, the behavior is also undefined. On the other hand, extra
arguments are simply ignored.
File: octave, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: C-Style I/O Functions
Numeric Input Conversions
-------------------------
This section describes the `scanf' conversions for reading numeric
values.
The `%d' conversion matches an optionally signed integer in decimal
radix.
The `%i' conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant.
For example, any of the strings `10', `0xa', or `012' could be read
in as integers under the `%i' conversion. Each of these specifies a
number with decimal value `10'.
The `%o', `%u', and `%x' conversions match unsigned integers in
octal, decimal, and hexadecimal radices, respectively.
The `%X' conversion is identical to the `%x' conversion. They both
permit either uppercase or lowercase letters to be used as digits.
Unlike the C language `scanf', Octave ignores the `h', `l', and `L'
modifiers.
File: octave, Node: String Input Conversions, Next: Binary I/O, Prev: Numeric Input Conversions, Up: C-Style I/O Functions
String Input Conversions
------------------------
This section describes the `scanf' input conversions for reading
string and character values: `%s' and `%c'.
The `%c' conversion is the simplest: it matches a fixed number of
characters, always. The maximum field with says how many characters to
read; if you don't specify the maximum, the default is 1. This
conversion does not skip over initial whitespace characters. It reads
precisely the next N characters, and fails if it cannot get that many.
The `%s' conversion matches a string of non-whitespace characters.
It skips and discards initial whitespace, but stops when it encounters
more whitespace after having read something.
For example, reading the input:
hello, world
with the conversion `%10c' produces `" hello, wo"', but reading the
same input with the conversion `%10s' produces `"hello,"'.
File: octave, Node: Binary I/O, Next: Temporary Files, Prev: String Input Conversions, Up: C-Style I/O Functions
Binary I/O
----------
Octave can read and write binary data using the functions `fread'
and `fwrite', which are patterned after the standard C functions with
the same names. The are able to automatically swap the byte order of
integer data and convert among ths supported floating point formats as
the data are read.
- Built-in Function: [VAL, COUNT] = fread (FID, SIZE, PRECISION, SKIP,
ARCH)
Read binary data of type PRECISION from the specified file ID FID.
The optional argument SIZE specifies the amount of data to read
and may be one of
`Inf'
Read as much as possible, returning a column vector.
`NR'
`[NR, Inf]'
Read as much as possible, returning a matrix with NR rows.
If the number of elements read is not an exact multiple of
NR, the last column is padded with zeros.
`[NR, NC]'
Read up to `NR * NC' elements, returning a matrix with NR
rows. If the number of elements read is not an exact multiple
of NR, the last column is padded with zeros.
If SIZE is omitted, a value of `Inf' is assumed.
The optional argument PRECISION is a string specifying the type of
data to read and may be one of
`"char"'
`"char*1"'
`"integer*1"'
`"int8"'
Single character.
`"signed char"'
`"schar"'
Signed character.
`"unsigned char"'
`"uchar"'
Unsigned character.
`"short"'
Short integer.
`"unsigned short"'
`"ushort"'
Unsigned short integer.
`"int"'
Integer.
`"unsigned int"'
`"uint"'
Unsigned integer.
`"long"'
Long integer.
`"unsigned long"'
`"ulong"'
Unsigned long integer.
`"float"'
`"float32"'
`"real*4"'
Single precision float.
`"double"'
`"float64"'
`"real*8"'
Double precision float.
`"integer*2"'
`"int16"'
Two byte integer.
`"integer*4"'
`"int32"'
Four byte integer.
The default precision is `"uchar"'.
The optional argument SKIP specifies the number of bytes to skip
before each element is read. If it is not specified, a value of 0
is assumed.
The optional argument ARCH is a string specifying the data format
for the file. Valid values are
`"native"'
The format of the current machine.
`"ieee-le"'
IEEE big endian.
`"ieee-be"'
IEEE little endian.
`"vaxd"'
VAX D floating format.
`"vaxg"'
VAX G floating format.
`"cray"'
Cray floating format.
Conversions are currently only supported for `"ieee-be"' and
`"ieee-le"' formats.
The data read from the file is returned in VAL, and the number of
values read is returned in `count'
- Built-in Function: COUNT = fwrite (FID, DATA, PRECISION, SKIP, ARCH)
Write data in binary form of type PRECISION to the specified file
ID FID, returning the number of values successfully written to the
file.
The argument DATA is a matrix of values that are to be written to
the file. The values are extracted in column-major order.
The remaining arguments PRECISION, SKIP, and ARCH are optional,
and are interpreted as described for `fread'.
The behavior of `fwrite' is undefined if the values in DATA are
too large to fit in the specified precision.
File: octave, Node: Temporary Files, Next: EOF and Errors, Prev: Binary I/O, Up: C-Style I/O Functions
Temporary Files
---------------
- Built-in Function: tmpnam ()
Return a unique temporary file name as a string.
Since the named file is not opened, by `tmpnam', it is possible
(though relatively unlikely) that it will not be available by the
time your program attempts to open it.
File: octave, Node: EOF and Errors, Next: File Positioning, Prev: Temporary Files, Up: C-Style I/O Functions
End of File and Errors
----------------------
- Built-in Function: feof (FID)
Return 1 if an end-of-file condition has been encountered for a
given file and 0 otherwise. Note that it will only return 1 if
the end of the file has already been encountered, not if the next
read operation will result in an end-of-file condition.
- Built-in Function: ferror (FID)
Return 1 if an error condition has been encountered for a given
file and 0 otherwise. Note that it will only return 1 if an error
has already been encountered, not if the next operation will
result in an error condition.
- Built-in Function: freport ()
Print a list of which files have been opened, and whether they are
open for reading, writing, or both. For example,
freport ()
-| number mode name
-|
-| 0 r stdin
-| 1 w stdout
-| 2 w stderr
-| 3 r myfile
File: octave, Node: File Positioning, Prev: EOF and Errors, Up: C-Style I/O Functions
File Positioning
----------------
Three functions are available for setting and determining the
position of the file pointer for a given file.
- Built-in Function: ftell (FID)
Return the position of the file pointer as the number of characters
from the beginning of the file FID.
- Built-in Function: fseek (FID, OFFSET, ORIGIN)
Set the file pointer to any location within the file FID. The
pointer is positioned OFFSET characters from the ORIGIN, which may
be one of the predefined variables `SEEK_CUR' (current position),
`SEEK_SET' (beginning), or `SEEK_END' (end of file). If ORIGIN is
omitted, `SEEK_SET' is assumed. The offset must be zero, or a
value returned by `ftell' (in which case ORIGIN must be `SEEK_SET'.
- Built-in Variable: SEEK_SET
- Built-in Variable: SEEK_CUR
- Built-in Variable: SEEK_END
These variables may be used as the optional third argument for the
function `fseek'.
- Built-in Function: frewind (FID)
Move the file pointer to the beginning of the file FID, returning
1 for success, and 0 if an error was encountered. It is
equivalent to `fseek (FID, 0, SEEK_SET)'.
The following example stores the current file position in the
variable `marker', moves the pointer to the beginning of the file, reads
four characters, and then returns to the original position.
marker = ftell (myfile);
frewind (myfile);
fourch = fgets (myfile, 4);
fseek (myfile, marker, SEEK_SET);
File: octave, Node: Plotting, Next: Matrix Manipulation, Prev: Input and Output, Up: Top
Plotting
********
All of Octave's plotting functions use `gnuplot' to handle the
actual graphics. There are two low-level functions, `gplot' and
`gsplot', that behave almost exactly like the corresponding `gnuplot'
functions `plot' and `splot'. A number of other higher level plotting
functions, patterned after the graphics functions found in MATLAB
version 3.5, are also available. These higher level functions are all
implemented in terms of the two low-level plotting functions.
* Menu:
* Two-Dimensional Plotting::
* Specialized Two-Dimensional Plots::
* Three-Dimensional Plotting::
* Plot Annotations::
* Multiple Plots on One Page::
File: octave, Node: Two-Dimensional Plotting, Next: Specialized Two-Dimensional Plots, Prev: Plotting, Up: Plotting
Two-Dimensional Plotting
========================
- Command: gplot RANGES EXPRESSION USING TITLE STYLE
Generate a 2-dimensional plot.
The RANGES, USING, TITLE, and STYLE arguments are optional, and
the USING, TITLE and STYLE qualifiers may appear in any order
after the expression. You may plot multiple expressions with a
single command by separating them with commas. Each expression
may have its own set of qualifiers.
The optional item RANGES has the syntax
[ x_lo : x_up ] [ y_lo : y_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y
axes and any of the individual limits may be omitted. A range
`[:]' indicates that the default limits should be used. This
normally means that a range just large enough to include all the
data points will be used.
The expression to be plotted must not contain any literal matrices
(e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
distinguish a plot range from a matrix of data.
See the help for `gnuplot' for a description of the syntax for the
optional items.
By default, the `gplot' command plots the second column of a matrix
versus the first. If the matrix only has one column, it is taken
as a vector of y-coordinates and the x-coordinate is taken as the
element index, starting with zero. For example,
gplot rand (100,1) with linespoints
will plot 100 random values and connect them with lines. When
`gplot' is used to plot a column vector, the indices of the
elements are taken as x values.
If there are more than two columns, you can choose which columns
to plot with the USING qualifier. For example, given the data
x = (-10:0.1:10)';
data = [x, sin(x), cos(x)];
the command
gplot [-11:11] [-1.1:1.1] \
data with lines, data using 1:3 with impulses
will plot two lines. The first line is generated by the command
`data with lines', and is a graph of the sine function over the
range -10 to 10. The data is taken from the first two columns of
the matrix because columns to plot were not specified with the
USING qualifier.
The clause `using 1:3' in the second part of this plot command
specifies that the first and third columns of the matrix `data'
should be taken as the values to plot.
In this example, the ranges have been explicitly specified to be a
bit larger than the actual range of the data so that the curves do
not touch the border of the plot.
- Command: gset OPTIONS
- Command: gshow OPTIONS
- Command: replot OPTIONS
In addition to the basic plotting commands, the whole range of
`gset' and `gshow' commands from `gnuplot' are available, as is
`replot'.
Note that in Octave 2.0, the `set' and `show' commands were
renamed to `gset' and `gshow' in order to allow for compatibility
with the MATLAB graphics and GUI commands in a future version of
Octave. (For now, the old `set' and `show' commands do work, but
they print an annoying warning message to try to get people to
switch to using `gset' and `gshow'.)
The `gset' and `gshow' commands allow you to set and show
`gnuplot' parameters. For more information about the `gset' and
`gshow' commands, see the documentation for `set' and `show' in
the `gnuplot' user's guide (also available on line if you run
`gnuplot' directly, instead of running it from Octave).
The `replot' command allows you to force the plot to be
redisplayed. This is useful if you have changed something about
the plot, such as the title or axis labels. The `replot' command
also accepts the same arguments as `gplot' or `gsplot' (except for
data ranges) so you can add additional lines to existing plots.
For example,
gset term tek40
gset output "/dev/plotter"
gset title "sine with lines and cosine with impulses"
replot "sin (x) w l"
will change the terminal type for plotting, add a title to the
current plot, add a graph of sin (x) to the plot, and force the
new plot to be sent to the plot device. This last step is
normally required in order to update the plot. This default is
reasonable for slow terminals or hardcopy output devices because
even when you are adding additional lines with a replot command,
gnuplot always redraws the entire plot, and you probably don't
want to have a completely new plot generated every time something
as minor as an axis label changes.
The command `shg' is equivalent to executing `replot' without any
arguments.
- Built-in Variable: automatic_replot
You can tell Octave to redisplay the plot each time anything about
it changes by setting the value of the builtin variable
`automatic_replot' to a nonzero value. Since this is fairly
inefficient, the default value is 0.
Note that NaN values in the plot data are automatically omitted, and
Inf values are converted to a very large value before calling gnuplot.
The MATLAB-style two-dimensional plotting commands are:
- Function File: plot (ARGS)
This function produces two-dimensional plots. Many different
combinations of arguments are possible. The simplest form is
plot (Y)
where the argument is taken as the set of Y coordinates and the X
coordinates are taken to be the indices of the elements, starting
with 1.
If more than one argument is given, they are interpreted as
plot (X, Y, FMT ...)
where Y and FMT are optional, and any number of argument sets may
appear. The X and Y values are interpreted as follows:
* If a single data argument is supplied, it is taken as the set
of Y coordinates and the X coordinates are taken to be the
indices of the elements, starting with 1.
* If the first argument is a vector and the second is a matrix,
the the vector is plotted versus the columns (or rows) of the
matrix. (using whichever combination matches, with columns
tried first.)
* If the first argument is a matrix and the second is a vector,
the the columns (or rows) of the matrix are plotted versus
the vector. (using whichever combination matches, with
columns tried first.)
* If both arguments are vectors, the elements of Y are plotted
versus the elements of X.
* If both arguments are matrices, the columns of Y are plotted
versus the columns of X. In this case, both matrices must
have the same number of rows and columns and no attempt is
made to transpose the arguments to make the number of rows
match.
If both arguments are scalars, a single point is plotted.
The FMT argument, if present is interpreted as follows. If FMT is
missing, the default gnuplot line style is assumed.
`-'
Set lines plot style (default).
`.'
Set dots plot style.
`@'
Set points plot style.
`-@'
Set linespoints plot style.
`^'
Set impulses plot style.
`L'
Set steps plot style.
`#'
Set boxes plot style.
`~'
Set errorbars plot style.
`#~'
Set boxerrorbars plot style.
`N'
Interpreted as the plot color if N is an integer in the range
1 to 6.
`NM'
If NM is a two digit integer and M is an integer in the range
1 to 6, M is interpreted as the point style. This is only
valid in combination with the `@' or `-@' specifiers.
`C'
If C is one of `"r"', `"g"', `"b"', `"m"', `"c"', or `"w"',
it is interpreted as the plot color (red, green, blue,
magenta, cyan, or white).
`+'
`*'
`o'
`x'
Used in combination with the points or linespoints styles,
set the point style.
The color line styles have the following meanings on terminals that
support color.
Number Gnuplot colors (lines)points style
1 red *
2 green +
3 blue o
4 magenta x
5 cyan house
6 brown there exists
Here are some plot examples:
plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")
This command will plot `y' with points of type 2 (displayed as
`+') and color 1 (red), `y2' with lines, `y3' with lines of color
4 (magenta) and `y4' with points displayed as `+'.
plot (b, "*")
This command will plot the data in the variable `b' will be plotted
with points displayed as `*'.
- Function File: hold ARGS
Tell Octave to `hold' the current data on the plot when executing
subsequent plotting commands. This allows you to execute a series
of plot commands and have all the lines end up on the same figure.
The default is for each new plot command to clear the plot device
first. For example, the command
hold on
turns the hold state on. An argument of `off' turns the hold state
off, and `hold' with no arguments toggles the current hold state.
- Function File: ishold
Return 1 if the next line will be added to the current plot, or 0
if the plot device will be cleared before drawing the next line.
- Function File: clearplot
- Function File: clg
Clear the plot window and any titles or axis labels. The name
`clg' is aliased to `clearplot' for compatibility with MATLAB.
The commands `gplot clear', `gsplot clear', and `replot clear' are
equivalent to `clearplot'. (Previously, commands like `gplot
clear' would evaluate `clear' as an ordinary expression and clear
all the visible variables.)
- Function File: closeplot
Close stream to the `gnuplot' subprocess. If you are using X11,
this will close the plot window.
- Function File: purge_tmp_files
Delete the temporary files created by the plotting commands.
Octave creates temporary data files for `gnuplot' and then sends
commands to `gnuplot' through a pipe. Octave will delete the
temporary files on exit, but if you are doing a lot of plotting
you may want to clean up in the middle of a session.
A future version of Octave will eliminate the need to use temporary
files to hold the plot data.
- Function File: axis (LIMITS)
Sets the axis limits for plots.
The argument LIMITS should be a 2, 4, or 6 element vector. The
first and second elements specify the lower and upper limits for
the x axis. The third and fourth specify the limits for the y
axis, and the fifth and sixth specify the limits for the z axis.
With no arguments, `axis' turns autoscaling on.
If your plot is already drawn, then you need to use `replot' before
the new axis limits will take effect. You can get this to happen
automatically by setting the built-in variable `automatic_replot'
to a nonzero value.
File: octave, Node: Specialized Two-Dimensional Plots, Next: Three-Dimensional Plotting, Prev: Two-Dimensional Plotting, Up: Plotting
Specialized Two-Dimensional Plots
=================================
- Function File: bar (X, Y)
Given two vectors of x-y data, `bar' produces a bar graph.
If only one argument is given, it is taken as a vector of y-values
and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but
not plotted. For example,
bar (x, y);
and
[xb, yb] = bar (x, y);
plot (xb, yb);
are equivalent.
- Function File: contour (Z, N, X, Y)
Make a contour plot of the three-dimensional surface described by
Z. Someone needs to improve `gnuplot''s contour routines before
this will be very useful.
- Function File: hist (Y, X)
Produce histogram counts or plots.
With one vector input argument, plot a histogram of the values with
10 bins. The range of the histogram bins is determined by the
range of the data.
Given a second scalar argument, use that as the number of bins.
Given a second vector argument, use that as the centers of the
bins, with the width of the bins determined from the adjacent
values in the vector.
Extreme values are lumped in the first and last bins.
With two output arguments, produce the values NN and XX such that
`bar (XX, NN)' will plot the histogram.
- Function File: loglog (ARGS)
Make a two-dimensional plot using log scales for both axes. See
the description of `plot' above for a description of the arguments
that `loglog' will accept.
- Function File: polar (THETA, RHO)
Make a two-dimensional plot given polar the coordinates THETA and
RHO.
- Function File: semilogx (ARGS)
Make a two-dimensional plot using a log scale for the X axis. See
the description of `plot' above for a description of the arguments
that `semilogx' will accept.
- Function File: semilogy (ARGS)
Make a two-dimensional plot using a log scale for the Y axis. See
the description of `plot' above for a description of the arguments
that `semilogy' will accept.
- Function File: stairs (X, Y)
Given two vectors of x-y data, bar produces a `stairstep' plot.
If only one argument is given, it is taken as a vector of y-values
and the x coordinates are taken to be the indices of the elements.
If two output arguments are specified, the data are generated but
not plotted. For example,
stairs (x, y);
and
[xs, ys] = stairs (x, y);
plot (xs, ys);
are equivalent.
File: octave, Node: Three-Dimensional Plotting, Next: Plot Annotations, Prev: Specialized Two-Dimensional Plots, Up: Plotting
Three-Dimensional Plotting
==========================
- Command: gsplot RANGES EXPRESSION USING TITLE STYLE
Generate a 3-dimensional plot.
The RANGES, USING, TITLE, and STYLE arguments are optional, and
the USING, TITLE and STYLE qualifiers may appear in any order
after the expression. You may plot multiple expressions with a
single command by separating them with commas. Each expression
may have its own set of qualifiers.
The optional item RANGES has the syntax
[ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data. The range for the y
and z axes and any of the individual limits may be omitted. A
range `[:]' indicates that the default limits should be used. This
normally means that a range just large enough to include all the
data points will be used.
The expression to be plotted must not contain any literal matrices
(e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
distinguish a plot range from a matrix of data.
See the help for `gnuplot' for a description of the syntax for the
optional items.
By default, the `gsplot' command plots each column of the
expression as the z value, using the row index as the x value, and
the column index as the y value. The indices are counted from
zero, not one. For example,
gsplot rand (5, 2)
will plot a random surface, with the x and y values taken from the
row and column indices of the matrix.
If parametric plotting mode is set (using the command `gset
parametric', then `gsplot' takes the columns of the matrix three
at a time as the x, y and z values that define a line in three
space. Any extra columns are ignored, and the x and y values are
expected to be sorted. For example, with `parametric' set, it
makes sense to plot a matrix like
1 1 3 2 1 6 3 1 9
1 2 2 2 2 5 3 2 8
1 3 1 2 3 4 3 3 7
but not `rand (5, 30)'.
The MATLAB-style three-dimensional plotting commands are:
- Function File: mesh (X, Y, Z)
Plot a mesh given matrices `x', and Y from `meshdom' and a matrix
Z corresponding to the X and Y coordinates of the mesh.
- Function File: meshdom (X, Y)
Given vectors of X and Y coordinates, return two matrices
corresponding to the X and Y coordinates of the mesh.
See the file `sombrero.m' for an example of using `mesh' and
`meshdom'.
- Built-in Variable: gnuplot_binary
The name of the program invoked by the plot command. The default
value is `"gnuplot"'. *Note Installation::.
- Built-in Variable: gnuplot_has_frames
If the value of this variable is nonzero, Octave assumes that your
copy of gnuplot has support for multiple frames that is included
in recent 3.6beta releases. It's initial value is determined by
configure, but it can be changed in your startup script or at the
command line in case configure got it wrong, or if you upgrade
your gnuplot installation.
- Function File: figure (N)
Set the current plot window to plot window N. This function
currently requires X11 and a version of gnuplot that supports
multiple frames.
- Built-in Variable: gnuplot_has_multiplot
If the value of this variable is nonzero, Octave assumes that your
copy of gnuplot has the multiplot support that is included in
recent 3.6beta releases. It's initial value is determined by
configure, but it can be changed in your startup script or at the
command line in case configure got it wrong, or if you upgrade
your gnuplot installation.
File: octave, Node: Plot Annotations, Next: Multiple Plots on One Page, Prev: Three-Dimensional Plotting, Up: Plotting
Plot Annotations
================
- Function File: grid
For two-dimensional plotting, force the display of a grid on the
plot.
- Function File: title (STRING)
Specify a title for the plot. If you already have a plot
displayed, use the command `replot' to redisplay it with the new
title.
- Function File: xlabel (STRING)
- Function File: ylabel (STRING)
- Function File: zlabel (STRING)
Specify x, y, and z axis labels for the plot. If you already have
a plot displayed, use the command `replot' to redisplay it with
the new labels.
File: octave, Node: Multiple Plots on One Page, Prev: Plot Annotations, Up: Plotting
Multiple Plots on One Page
==========================
The following functions all require a version of `gnuplot' that
supports the multiplot feature.
- Function File: mplot (X, Y)
- Function File: mplot (X, Y, FMT)
- Function File: mplot (X1, Y1, X2, Y2)
This is a modified version of the `plot' function that works with
the multiplot version of `gnuplot' to plot multiple plots per page.
This plot version automatically advances to the next subplot
position after each set of arguments are processed.
See the description of the PLOT function for the various options.
- Function File: multiplot (XN, YN)
Sets and resets multiplot mode.
If the arguments are non-zero, `multiplot' will set up multiplot
mode with XN, YN subplots along the X and Y axes. If both
arguments are zero, `multiplot' closes multiplot mode.
- Function File: oneplot ()
If in multiplot mode, switches to single plot mode.
- Function File: plot_border (...)
Multiple arguments allowed to specify the sides on which the border
is shown. Allowed arguments include:
`"blank"'
No borders displayed.
`"all"'
All borders displayed
`"north"'
North Border
`"south"'
South Border
`"east"'
East Border
`"west"'
West Border
The arguments may be abbreviated to single characters. Without any
arguments, `plot_border' turns borders off.
- Function File: subplot (ROWS, COLS, INDEX)
- Function File: subplot (RCN)
Sets `gnuplot' in multiplot mode and plots in location given by
index (there are COLS by ROWS subwindows).
Input:
ROWS
Number of rows in subplot grid.
COLUMNS
Number of columns in subplot grid.
INDEX
Index of subplot where to make the next plot.
If only one argument is supplied, then it must be a three digit
value specifying the location in digits 1 (rows) and 2 (columns)
and the plot index in digit 3.
The plot index runs row-wise. First all the columns in a row are
filled and then the next row is filled.
For example, a plot with 4 by 2 grid will have plot indices
running as follows:
+-----+-----+-----+-----+
| 1 | 2 | 3 | 4 |
+-----+-----+-----+-----+
| 5 | 6 | 7 | 8 |
+-----+-----+-----+-----+
- Function File: subwindow (XN, YN)
Sets the subwindow position in multiplot mode for the next plot.
The multiplot mode has to be previously initialized using the
`multiplot' function, otherwise this command just becomes an alias
to `multiplot'
- Function File: top_title (STRING)
- Function File: bottom_title (STRING)
Makes a title with text STRING at the top (bottom) of the plot.
File: octave, Node: Matrix Manipulation, Next: Arithmetic, Prev: Plotting, Up: Top
Matrix Manipulation
*******************
There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix. For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value. Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.
* Menu:
* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::
File: octave, Node: Finding Elements and Checking Conditions, Next: Rearranging Matrices, Prev: Matrix Manipulation, Up: Matrix Manipulation
Finding Elements and Checking Conditions
========================================
The functions `any' and `all' are useful for determining whether any
or all of the elements of a matrix satisfy some condition. The `find'
function is also useful in determining which elements of a matrix meet
a specified condition.
- Built-in Function: any (X)
For a vector argument, return 1 if any element of the vector is
nonzero.
For a matrix argument, return a row vector of ones and zeros with
each element indicating whether any of the elements of the
corresponding column of the matrix are nonzero. For example,
any (eye (2, 4))
=> [ 1, 1, 0, 0 ]
To see if any of the elements of a matrix are nonzero, you can use
a statement like
any (any (a))
- Built-in Function: all (X)
The function `all' behaves like the function `any', except that it
returns true only if all the elements of a vector, or all the
elements in a column of a matrix, are nonzero.
Since the comparison operators (*note Comparison Ops::.) return
matrices of ones and zeros, it is easy to test a matrix for many
things, not just whether the elements are nonzero. For example,
all (all (rand (5) < 0.9))
=> 0
tests a random 5 by 5 matrix to see if all of it's elements are less
than 0.9.
Note that in conditional contexts (like the test clause of `if' and
`while' statements) Octave treats the test as if you had typed `all
(all (condition))'.
- Function File: [ERR, Y1, ...] = common_size (X1, ...)
Determine if all input arguments are either scalar or of common
size. If so, ERR is zero, and YI is a matrix of the common size
with all entries equal to XI if this is a scalar or XI otherwise.
If the inputs cannot be brought to a common size, errorcode is 1,
and YI is XI. For example,
[errorcode, a, b] = common_size ([1 2; 3 4], 5)
=> errorcode = 0
=> a = [ 1, 2; 3, 4 ]
=> b = [ 5, 5; 5, 5 ]
This is useful for implementing functions where arguments can
either be scalars or of common size.
- Function File: diff (X, K)
If X is a vector of length N, `diff (X)' is the vector of first
differences X(2) - X(1), ..., X(n) - X(n-1).
If X is a matrix, `diff (X)' is the matrix of column differences.
The second argument is optional. If supplied, `diff (X, K)',
where K is a nonnegative integer, returns the K-th differences.
- Mapping Function: isinf (X)
Return 1 for elements of X that are infinite and zero otherwise.
For example,
isinf ([13, Inf, NaN])
=> [ 0, 1, 0 ]
- Mapping Function: isnan (X)
Return 1 for elements of X that are NaN values and zero otherwise.
For example,
isnan ([13, Inf, NaN])
=> [ 0, 0, 1 ]
- Mapping Function: finite (X)
Return 1 for elements of X that are NaN values and zero otherwise.
For example,
finite ([13, Inf, NaN])
=> [ 1, 0, 0 ]
- Loadable Function: find (X)
Return a vector of indices of nonzero elements of a matrix. To
obtain a single index for each matrix element, Octave pretends
that the columns of a matrix form one long vector (like Fortran
arrays are stored). For example,
find (eye (2))
=> [ 1; 4 ]
If two outputs are requested, `find' returns the row and column
indices of nonzero elements of a matrix. For example,
[i, j] = find (2 * eye (2))
=> i = [ 1; 2 ]
=> j = [ 1; 2 ]
If three outputs are requested, `find' also returns a vector
containing the the nonzero values. For example,
[i, j, v] = find (3 * eye (2))
=> i = [ 1; 2 ]
=> j = [ 1; 2 ]
=> v = [ 3; 3 ]